# Setup linting for your OpenAPI Spec

To ensure that your SDKs are free of bugs & ergonomic (i.e. meaningful
namespaces, succinct method name, and legible class names), Konfig has created
a comprehensive set of rules that your OAS must pass. All lint rules and their
explanations are documented [here](/docs/lint-rules).

## Methods

There are four ways to lint your spec:

1. [GitHub Action](#github-action-setup)
2. [VSCode Extension](#vscode-extension-or-cli-setup)
3. [CLI](#vscode-extension-or-cli-setup)
4. [REST API](#rest-api)

## Required Setup

Ensure you have the `konfig-cli` installed by running

```bash
npm install -g konfig-cli
```

## GitHub Action Setup

To setup GitHub Action copy the following template to `.github/workflows/konfig-lint.yaml` and configure the following values:

<CH.Section>
1. [Target branch](focus://6)
2. [Path to OAS](focus://25[26:45])

```yaml .github/workflows/konfig-lint.yaml
name: "konfig-lint-openapi-spec"
on:
  pull_request:
  push:
    branches:
      - main
jobs:
  konfig-lint-openapi-spec:
    runs-on: ubuntu-latest
    env:
      CLI_VERSION: 1.0.181
    steps:
      - uses: actions/checkout@v3
      - name: Cache node_modules
        id: cache-npm
        uses: actions/cache@v3
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.CLI_VERSION }}
      - name: Install Konfig CLI
        run: npm install -g konfig-cli@$CLI_VERSION
      - name: Initialize Linting Rules
        run: konfig init -s
      - name: Lint OpenAPI Spec
        run: konfig lint path/to/openapi.yaml
```

</CH.Section>

Commit and push the generated file:

```bash focus=13,16
~/Git/my-repo
❯ git status
On branch master
Your branch is up to date with 'origin/master'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .github/

nothing added to commit but untracked files present (use "git add" to track)

~/Git/my-repo
❯ git add -A

~/Git/my-repo
❯ git commit -m "Commit Konfig lint GitHub action"
[master 83d1f7e] Commit Konfig lint GitHub action
 1 file changed, 26 insertions(+)
 create mode 100644 .github/workflows/konfig-lint.yaml
```

On every PR or commit to your target branch the lint workflow will fail if any
warnings or errors occur when linting your OAS.

![GitHub Action Lint Error](/img/github-action-lint-error.png)

## VSCode Extension or CLI Setup

Initialize your target repository (the one that has your OpenAPI spec) with:

```bash focus=1
❯ konfig init -s
Downloading Konfig's lint rules... done
Setting up Spectral... done
```

Commit the generated files

```bash focus=16,19
~/Git/my-repo
❯ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .konfig/
        .spectral.yaml
        .vscode/

nothing added to commit but untracked files present (use "git add" to track)

~/Git/my-repo
❯ git add -A

~/Git/my-repo
❯ git commit -m "Commit Konfig linting ruleset and VSCode settings"
[master 06c577e] Commit Konfig linting ruleset and VSCode settings
 4 files changed, 28 insertions(+)
 create mode 100644 .konfig/ruleset.js
 create mode 100644 .spectral.yaml
 create mode 100644 .vscode/extensions.json
 create mode 100644 .vscode/settings.json
```

<Admonition type="info">

To update your ruleset to the latest verson simply run

```bash
konfig init -s
```

And commit the updated ruleset.

</Admonition>

### Linting with VSCode Extension

When opening VSCode to your repo, you will be prompted to install the [Spectral](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral) extension.

![VSCode Popup](/img/vscode-popup.png)

Click `Install` to install the Spectral extension. When viewing any OAS, you will see inline errors.

![VSCode Error](/img/vscode-lint-error.png)

To see all the errors, open the "PROBLEMS" tab at the bottom
of VSCode.

![VSCode Problems Tab](/img/vscode-problems-tab.png)

Make sure that showing all problems is enabled

![VSCode Problems Filter](/img/vscode-problems-filter.png)

### Linting with CLI

<CH.Section>
To lint with CLI run `konfig lint` inside the directory that contains your `konfig.yaml` file.

```bash focus=1
❯ konfig lint

/api.yaml
 22:10  warning  operation-operationId  Operation must have "operationId" for generated SDK method names.  paths./pet.post

✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints)
```

</CH.Section>

## REST API

For access to the REST API please [setup a time](/schedule-demo) to talk and we will get you setup.
